メインコンテンツまでスキップ

Web SDK

自分の Web ページに AR Clip VPS を追加します。Web SDK は、訪問者が VPS マップ上のどこにいるかをブラウザーの中で特定します。アプリのインストールは不要です。

始める前に​

  • API キー。 入手するには、サポート からご連絡ください。
  • マップのロケーション ID。 どのマップにもあります。詳しくは はじめに を見てください。
  • HTTPS で配信するページ。 ブラウザーは、安全なページにしかカメラとモーションセンサーを使わせません。localhost も安全なページとして扱われます。

インストール​

npm install @web-ar-studio/webar-engine-sdk

パッケージは npm で公開されていて、TypeScript の型定義も含まれています。

VPS を開始する​

VPS は、ワールドトラッキングのセッションの中で動きます。init() に vps を追加し、ロケーション ID を並べます。SDK 自体は何も描画しないので、three.js、Babylon.js、PlayCanvas、素の WebGL など、好きなエンジンでシーンを描画してください。

import * as THREE from "three";
import WAS, {
  PROJECT_MODE_SLAM,
  TRIGGER_MODE_SLAM,
  CAMERA_MODE_ENVIRONMENT,
  PROVIDER_8THWALL,
  EVENT_FRAME,
  EVENT_VPS_READY,
  EVENT_VPS_LOCALIZED,
  EVENT_VPS_NOT_LOCALIZED,
  EVENT_VPS_ERROR,
} from "@web-ar-studio/webar-engine-sdk";

const was = new WAS();

const { canvas, context } = await was.init({
  apiKey: "your-api-key",
  mode: PROJECT_MODE_SLAM,
  cameraMode: CAMERA_MODE_ENVIRONMENT,
  container: document.querySelector("#ar"),
  triggers: [{ id: 1, mode: TRIGGER_MODE_SLAM, source: null }],
  vps: { locationIds: ["your-location-id"] },
});

const renderer = new THREE.WebGLRenderer({ canvas, context });

was.on(EVENT_VPS_READY, () => console.log("VPS started"));
was.on(EVENT_VPS_LOCALIZED, ({ locationId, offset }) => {
  console.log("Found the place on map", locationId, offset);
});
was.on(EVENT_VPS_NOT_LOCALIZED, ({ status, statusDescription }) => {
  console.log("Not found yet:", status, statusDescription);
});
was.on(EVENT_VPS_ERROR, (message) => console.warn("VPS error:", message));

// トラッキングと VPS は、フレームのコールバックと一緒に始まります。タップで登録してください。
// WebXR と iPhone のモーションセンサーには、ユーザーの操作が必要です。
startButton.onclick = () =>
  was.on(EVENT_FRAME, () => renderer.render(scene, camera));

locationIds を省くと、VPS は特定のマップに絞らずにグローバルにローカライズします。時間がかかるので、requestTimeoutMs を大きくしてください。

vps は init() に渡しましょう

Android の Chrome では、VPS 用のカメラへのアクセスはセッションの開始時にしか許可されません。vps なしで始めると、そのセッションではあとから VPS を有効にできず、setupVPS() が VpsError を投げます。

動作する環境​

SDK は、デバイスに合わせてトラッキングエンジン（provider）を選びます。既定値の "auto" では、まず webxr、次に 8thwall を試します。

エンジン動作する場所VPS
webxrAndroid の Chrome対応。SDK がシーンをマップに合わせます。
8thwallWebXR のないブラウザー（iPhone の Safari など）対応。offset はご自身で適用します。
arclip-webar明示的に選んだときだけ非対応

マップにコンテンツを置く​

コンテンツは、VPS マップの座標で配置します。VPS が場所を特定すると、EVENT_VPS_LOCALIZED が offset を渡します。これは、トラッキングの世界をマップに重ねるための移動量です。

  • webxr では、SDK がすでに offset を滑らかに適用しているので、マップのコンテンツは正しい位置に表示されます。
  • 8thwall では、SDK は offset を知らせるだけです。マップのコンテンツを 1 つのグループにまとめ、ローカライズのたびに、そのグループに offset の逆変換を設定します。
const mapRoot = new THREE.Group(); // マップの座標で配置したものすべて
scene.add(mapRoot);

was.on(EVENT_VPS_LOCALIZED, ({ offset }) => {
  if (was.getActiveProviderId() !== PROVIDER_8THWALL) return; // webxr では SDK が自分で適用します
  const { position: p, orientation: q } = offset;
  new THREE.Matrix4()
    .compose(
      new THREE.Vector3(p.x, p.y, p.z),
      new THREE.Quaternion(q.x, q.y, q.z, q.w),
      new THREE.Vector3(1, 1, 1),
    )
    .invert()
    .decompose(mapRoot.position, mapRoot.quaternion, mapRoot.scale);
});

SDK が結果を採用するのは、一致の信頼度が十分に高く、前回の結果からの移動が人の歩ける範囲に収まるときだけです。それ以外は EVENT_VPS_NOT_LOCALIZED として届きます。このため、長い廊下のように似た場所が続くところでも、コンテンツが飛びません。

イベント​

イベント受け取る内容
EVENT_VPS_READYなし。VPS が開始しました。
EVENT_VPS_LOCALIZEDlocationId、offset（position、orientation）、trackingPosition、trackingRotation、vpsPosition、vpsRotation、timestamp
EVENT_VPS_NOT_LOCALIZEDstatus、statusDescription、failCount
EVENT_VPS_ERRORエラーメッセージ（文字列）

VPS を制御する​

メソッド動作
startVPS()、stopVPS()ローカライズを再開、または一時停止します
isVPSActive()VPS が動いているかどうかを返します
setVPSLocationIds(ids)別のマップに切り替えます。空のリストを渡すと、グローバルにローカライズします
setupVPS(config)セッションの途中で VPS の設定を変えます
updateVPSSession()新しい VPS セッションを始めます。それまでの結果は、新しい結果に影響しなくなります
resetTracking()VPS の補正を取り消して、やり直します。誤った結果が出たあとなどに使います

設定​

vps のフィールドはすべて省略できます。apiKey は SDK が init() から引き継ぐので、もう一度書く必要はありません。

フィールド既定値内容
locationIdsなしカメラの映像と照らし合わせるマップ。省くと、VPS はグローバルにローカライズします。
captureInterval2500ローカライズのリクエストの間隔（ms）
requestTimeoutMs20000応答を待つ時間（ms）
maxFailsCount5何回続けて失敗したら、SDK が新しい VPS セッションを始めるか
imageFormat"jpeg""jpeg" または "webp"。WebP は、WebP を読めるサーバーでだけ使ってください。ブラウザーが WebP をエンコードできない場合、SDK は JPEG を送ります。
jpegQuality1画像の品質（0〜1）
targetWidth、targetHeight540、960サーバーに送るフレームのサイズ
minInlierRatio、minNumInliers0.6、600一致を採用するのに必要な信頼度
maxJumpBaseMeters、maxJumpSpeedMps3、2新しい結果が前回の結果からどこまで離れてよいか。maxJumpBaseMeters に、前回の結果からの秒数 × maxJumpSpeedMps を足した距離です
serverUrlAR Clip VPS別の VPS サーバー
sendApiKeyHeadertrueキーを x-vps-apikey ヘッダーで送ります。このヘッダーを受け付けない自前のサーバーを使うときだけオフにしてください。

エラー​

このセッションで VPS を動かせない場合、init() または VPS のメソッドは、VpsError（定数 VPS_ERROR）という名前のエラーで失敗します。開始後のエラー（リクエストの失敗など）は EVENT_VPS_ERROR で届きます。

さらに詳しく​

  • パッケージの README に、ほかのトラッキングモード、アンカー、three.js での完全なセットアップが載っています。
  • コードを書かずに VPS を設定するなら、AR Clip Studio の VPS シーン を使ってください。

次へ： 対応デバイス — スマートフォン、ブラウザー、ヘッドセット。